home *** CD-ROM | disk | FTP | other *** search
/ Aminet 33 / Aminet 33 - October 1999.iso / Aminet / docs / misc / amigapl.9903.lzh / amigapl.9903 / pci.lzx / PCI_Docs / pciexpansion.doc < prev    next >
Encoding:
Text File  |  1998-04-16  |  13.1 KB  |  396 lines
  1. TABLE OF CONTENTS
  2.  
  3. pciexpansion.library/--background--
  4. pciexpansion.library/AddPCIDev
  5. pciexpansion.library/AllocPCIDev
  6. pciexpansion.library/FindPCIDev
  7. pciexpansion.library/FreePCIDev
  8. pciexpansion.library/GetPCIReg
  9. pciexpansion.library/PutPCIReg
  10. pciexpansion.library/RemPCIDev
  11.  
  12. pciexpansion.library/--background--        pciexpansion.library/--background--
  13.  
  14.  
  15.     PURPOSE
  16.    pciexpansion.library is module responsible for integrating
  17.    PCI cards with Amiga system. During initialization this library
  18.    scans PCI slots. Each detected PCI card is configured (PCI) and
  19.    defined in AmigaOS expansion.library. PCI configuration settings
  20.    are stored in pciexpansion.library's private list.
  21.  
  22.     PCI Configuration Registers (shown as a structure)
  23.    
  24.    /* pci card configuration header format  */
  25.    /* Can be accessed by Get/PutPCIReg (RW) */
  26.    /* or via FindPCIDev (RO)                */
  27.    struct PCICfg {
  28.        /* offset 0x0 */
  29.           struct pci_id {
  30.          ULONG    did     : 16;   /* Device ID.                     */
  31.          ULONG    vid     : 16;   /* Vendor ID. 0xFFFF - slot empty */
  32.           }       pcie_id;
  33.        /* offset 0x4 */
  34.        struct pci_cs {
  35.            ULONG    d_pe    :  1;   /* Detected Parity Error.         */
  36.            ULONG    s_serr  :  1;   /* Signaled SERR#.                */
  37.            ULONG    r_ma    :  1;   /* Received Master-Abort.         */
  38.            ULONG    r_ta    :  1;   /* Received Target-Abort.         */
  39.            ULONG    s_ta    :  1;   /* Signaled Target-Abort.         */
  40.            ULONG    devsel  :  2;   /* DEVSEL timing.                 */
  41.            ULONG    dp_d    :  1;   /* Data Parity Detected.          */
  42.            ULONG    tfbbc   :  1;   /* Target Fast Back to Back       */
  43.                 /* Capable.               */
  44.            ULONG    udfs    :  1;   /* User Definable Features        */
  45.                 /* Support.            */
  46.            ULONG    dev66   :  1;   /* Device 66 MHz Capable.         */
  47.            ULONG    res1    :  5;   /*      PCI Reserved.             */
  48.            ULONG    res2    :  6;   /*      PCI Reserved.             */
  49.            ULONG    mfbbc   :  1;   /* Master Fast Back-to-Back       */
  50.                 /* Enable.                */
  51.            ULONG    serr_en :  1;   /* SERR# Enable.                  */
  52.            ULONG    step    :  1;   /* Data/address stepping.         */
  53.            ULONG    peresp  :  1;   /* Parity Error Response.         */
  54.            ULONG    vgaps   :  1;   /* VGA Palette Snoop.             */
  55.            ULONG    mwi_en  :  1;   /* Memory Write and Invalidate    */
  56.                 /* Enable.             */
  57.            ULONG    sca     :  1;   /* Special Cycles action.         */
  58.            ULONG    bm      :  1;   /* Bus Master.                    */
  59.            ULONG    ms      :  1;   /* Memory Space.                  */
  60.            ULONG    ios     :  1;   /* I/O Space.                     */
  61.        }       pcie_cs;
  62.        /* offset 0x8 */
  63.        struct pci_class {
  64.            ULONG    base    :  8;   /* Base Class Code.               */
  65.            ULONG    sub     :  8;   /* Sub Class Code.                */
  66.            ULONG    prog    :  8;   /* Programming Interface.         */
  67.            ULONG    revid   :  8;   /* Revision ID.                   */
  68.        }       pcie_class;
  69.        /* offset 0xC */
  70.        struct pci_misc0 {
  71.            ULONG    bistc   :  1;   /* BIST Capable.                  */
  72.            ULONG    sbist   :  1;   /* Start BIST.                    */
  73.            ULONG    res1    :  2;   /*     PCI Reserved.              */
  74.            ULONG    ccode   :  4;   /* Completion Code.               */
  75.            ULONG    mfunct  :  1;   /* Multifunction Device.          */
  76.            ULONG    layout  :  7;   /* Configuration Space Layout.    */
  77.            ULONG    ltimer  :  5;   /* Latency Timer.                 */
  78.            ULONG    zero1   :  7;   /* Zeros.                         */
  79.            ULONG    cline   :  2;   /* CacheLine Size.                */
  80.            ULONG    zero2   :  2;   /* Zeros.                         */
  81.        }       pcie_misc0;
  82.        /* offsets 0x10 - 0x24 */
  83.        /* base address registers - bit 0 selects space */
  84.        /* 1 - IO space, 0 - memory space               */
  85.        /* all unused bits are hardwired to 0           */
  86.        /* to determine board size write all 1's        */
  87.        /* and read. All used address line will be 1's  */
  88.        /* Most significant 0's determines board size   */
  89.        union  pci_base_address {
  90.            struct pci_mem_addr {
  91.               ULONG   ba    : 28;   /* Base Address.                  */
  92.               ULONG   pref  :  1;   /* Prefetchable                   */
  93.               ULONG   type  :  2;   /* 00 - locate anywhere in 32bit  */
  94.                 /*      space                     */
  95.                                     /* 01 - locate below 1MB          */
  96.                                     /* 10 - locate anywhare in 64bit  */
  97.                 /*      space                     */
  98.                                     /* 11 - reserved                  */
  99.               ULONG   space :  1;   /* PCI Bus Address Space.         */
  100.                                     /* 0 - memory space               */
  101.            } pcie_mem_addr;
  102.            struct pci_io_addr {
  103.               ULONG   ba    : 30;   /* Base Address.                  */
  104.               ULONG   zero1 :  1;   /* Zeros.                         */
  105.               ULONG   space :  1;   /* PCI Bus Address Space.         */
  106.                                     /* 1 - IO space                   */
  107.            } pcie_io_addr;
  108.            ULONG      valUlong;     /* if you prefer to mask bits     */
  109.        }       pcie_baddr[6];       /* up to 6 address registers     */
  110.        /* offset 0x28 */
  111.        ULONG   pcie_CISptr;         /* Cardbus CIS pointer            */
  112.        /* offset 0x2c */
  113.        struct pci_sid {
  114.            ULONG    sid     : 16;   /* Subsystem ID.                  */
  115.            ULONG    svid    : 16;   /* Subsystem Vendor ID.           */
  116.        }       pcie_sid;
  117.        /* offset 0x30 */
  118.        /* ROM base address - bit 0 enables ROM support */
  119.        union pci_rom_addr
  120.            struct {
  121.                ULONG  ba    : 21;   /* Base Address.                  */
  122.                ULONG  zero1 : 10;   /* Zeros.                         */
  123.                ULONG  ena   :  1;   /* ROM enable                     */
  124.            } bits;
  125.            ULONG valUlong;
  126.        }       pcie_rom_addr;
  127.        /* offset 0x34 */
  128.        ULONG   pci_Reserved1;
  129.        /* offset 0x38 */
  130.        ULONG   pci_Reserved2;
  131.        /* offset 0x3c */
  132.        struct pci_misc1 {
  133.            ULONG    max_lat     :  8;   /* Maximum Latency.           */
  134.            ULONG    min_gnt     :  8;   /* Minimum Grant.             */
  135.            ULONG    int_pin     :  8;   /* Interrupt Pin.             */
  136.            ULONG    int_line    :  8;   /* Interrupt Line.            */
  137.        }       pcie_misc1;
  138.    };
  139.  
  140.     Structure PCIConfDev
  141.    This structure is used by pciexpansion.library to hold
  142.    PCI configuration information and link this information
  143.    with expansion.library Zorro information.
  144.  
  145.    struct  PCIConfDev {
  146.        struct Node DevNode;        /* list pointers               */
  147.        struct PCICfg Config;       /* PCI information             */
  148.        UBYTE  bitsizes[6];         /* see micronik_pci.resource   */
  149.        UBYTE  ROMbitsize;
  150.        struct ConfigDev * ExpansionDev; /* link with expansion.library */
  151.        struct PCIExpDev * next; 
  152.        UBYTE  SlotNo;           /* PCI slot number             */
  153.    };
  154.  
  155.     Cooperation with expansion.library
  156.  
  157.    Each PCI card is defined in system using expansion.library
  158.    AddConfigDev function. Unless card has a ROM-based driver, it is
  159.    defined with cd_Manufacturer = 3855 (Micronik) and
  160.    cd_Product = 149 (unrecognized PCI card). Other ProductID used
  161.    by PCI software/hardware are:
  162.  
  163.             147 - PCI window 
  164.             148 - PCI bridge registers.
  165.  
  166.    If PCI card has a ROM with Amiga specific driver (image), both
  167.    cd_Manufacturer and cd_Product can be defined in this ROM.
  168.    (feature not implemented yet)
  169.  
  170.  
  171. -------
  172. pciexpansion.library/AddPCIDev                 pciexpansion.library/AddPCIDev
  173.  
  174.    NAME
  175.    AddPCIDev - add a new PCIConfDev structure to the 
  176.           pciexpansion.library list.
  177.  
  178.    SYNOPSIS
  179.    AddPCIDev( PCIConfDev )
  180.                  A0
  181.  
  182.    FUNCTION
  183.    (Not typically called by user code)
  184.  
  185.    This routine adds the specified PCIConfDev structure to the
  186.    list of PCI Devices in the system.
  187.  
  188.    INPUTS
  189.    configDev - a valid PCIConfDev structure.
  190.  
  191.    RESULTS
  192.  
  193.    EXCEPTIONS
  194.  
  195.    SEE ALSO
  196.    RemPCIDev
  197.  
  198.    BUGS
  199.  
  200.  
  201. pciexpansion.library/AllocPCIDev             pciexpansion.library/AllocPCIDev
  202.  
  203.    NAME
  204.    AllocConfigDev - allocate a PCIConfDev structure
  205.  
  206.    SYNOPSIS
  207.    PCIconfDev = AllocPCIDev()
  208.    D0
  209.  
  210.    FUNCTION
  211.    This routine returns the address of a PCIConfDev structure.
  212.    It is provided so new fields can be added to the structure
  213.    without breaking old, existing code.  The structure is cleared
  214.    when it is returned to the user.
  215.  
  216.    INPUTS
  217.  
  218.    RESULTS
  219.    PCIconfDev - either a valid PCIConfDev structure or NULL.
  220.  
  221.    EXCEPTIONS
  222.  
  223.    SEE ALSO
  224.    FreePCIDev
  225.  
  226.    BUGS
  227.  
  228.  
  229. pciexpansion.library/FindPCIDev               pciexpansion.library/FindPCIDev
  230.  
  231.    NAME
  232.    FindPCIDev - find a matching PCIConfDev entry
  233.  
  234.    SYNOPSIS
  235.    PCIConfDev = FindPCIDev( start, selection )
  236.    D0                         A0       A1  
  237.  
  238.    struct PCIConfDev * FindPCIDev(struct PCIConfDev *, struct Tagitem *)
  239.  
  240.    FUNCTION
  241.    This routine searches the list of existing PCIConfDev
  242.    structures in the system and looks for one that matches
  243.    specified selection parameters. You can specify any
  244.    number of parameters - returned structure matches
  245.    all of them.
  246.  
  247.    If the start is NULL the the search is from the
  248.    start of the list of configuration devices.  If it is
  249.    not null then it searches from the first configuration
  250.    device entry AFTER start.
  251.  
  252.    INPUTS
  253.    start - a valid PCIConfDev structure, or NULL to start
  254.       from the start of the list.
  255.    selection - (optional) array of TagItem structures with
  256.           parameters/value pairs. 
  257.  
  258.    RESULTS
  259.    PCIConfDev - the next PCIConfDev entry that matches the
  260.            specified parameters, or NULL if there
  261.            are no more matches.
  262.  
  263.    EXAMPLES
  264.    struct TagItem pcitags[] = 
  265.       {
  266.                    {PCIE_VENDORID, 0x5333},   /* S3 Incorporated  */
  267.                    {PCIE_BASECLASSCODE, 0x3}, /* Gfx card         */
  268.                    {TAG_DONE, 0 } 
  269.       };
  270.  
  271.    /* to find all configdevs of the proper type */
  272.    struct PCIConfDev *pcd = NULL;
  273.  
  274.    /* for all Gfx cards made by S3 Incorporated */
  275.    while( pcd = FindConfigDev( pcd, tags ) ) {
  276.       /* do something with the returned PCIConfDev */
  277.    }
  278.  
  279.    SEE ALSO
  280.  
  281.    BUGS
  282.  
  283.  
  284. pciexpansion.library/FreePCIDev               pciexpansion.library/FreePCIDev
  285.  
  286.    NAME
  287.    FreePCIDev - free a PCIConfDev structure
  288.  
  289.    SYNOPSIS
  290.    FreePCIDev( PCIconfDev )
  291.                   A1
  292.  
  293.    FUNCTION
  294.    This routine frees a PCIConfDev structure as returned by
  295.    AllocPCIDev.
  296.  
  297.    INPUTS
  298.    PCIconfDev - a valid PCIConfDev structure.
  299.  
  300.    RESULTS
  301.  
  302.    EXCEPTIONS
  303.  
  304.    SEE ALSO
  305.    AllocPCIDev
  306.  
  307.    BUGS
  308.  
  309.  
  310. pciexpansion.library/GetPCIReg                  pciexpansion.library/GetPCIReg
  311.  
  312.    NAME
  313.    GetPCIReg - Read PCI configuration register.
  314.  
  315.    SYNOPSIS
  316.    value = GetPCIReg( board, offset )
  317.    D0                   A0     D0
  318.  
  319.    ULONG GetPCIReg(struct PCIConfDev, UBYTE)
  320.  
  321.    FUNCTION
  322.    This function is higher level version of micronik_pci.resource
  323.    ReadCfgReg function. GetPCIReg function updates all
  324.    information in pciexpansion.library structures.
  325.    You need to specify PCIConfBoard pointer instead of
  326.    slot number.
  327.  
  328.    INPUTS
  329.    board - a pointer to the valid PCIConfDev structure.
  330.    offset - a logical offset of configuration register
  331.  
  332.    RESULTS
  333.    value - the configuration register value.
  334.  
  335.  
  336.    SEE ALSO
  337.    PutPCIReg, micronik_pci.resource/ReadCfgReg
  338.  
  339.  
  340. pciexpansion.library/PutPCIReg                  pciexpansion.library/PutPCIReg
  341.  
  342.    NAME
  343.    PutPCIReg - Write PCI configuration register.
  344.  
  345.    SYNOPSIS
  346.    PutPCIReg( board, offset, value )
  347.            A0     D0      D1
  348.  
  349.    PutPCIReg(struct PCIConfDev *, UBYTE, ULONG)
  350.  
  351.    FUNCTION
  352.    PutPCIReg writes a new value to a PCI configuration register of
  353.    specified PCI card. This function also updares information 
  354.    stored in pciexpansion.library structures.
  355.    You need to specify PCIConfBoard pointer instead of
  356.    slot number.
  357.  
  358.    INPUTS
  359.    board - a pointer to the valid PCIConfDev structure.
  360.    offset - a logical offset of configuration register
  361.    value - the data to be written to the configuration
  362.       register
  363.  
  364.    SEE ALSO
  365.    GetPCIReg, micronik_pci.resource/WriteCfgReg
  366.  
  367.  
  368. pciexpansion.library/RemPCIDev                 pciexpansion.library/RemPCIDev
  369.  
  370.    NAME
  371.    RemPCIDev - remove a PCIConfDev structure from the system
  372.  
  373.    SYNOPSIS
  374.    RemConfigDev( PCIconfDev )
  375.                  A0
  376.  
  377.    FUNCTION
  378.    (Not typically called by user code)
  379.  
  380.    This routine removes the specified PCIConfDev structure from the
  381.    list of PCI Devices in the system.
  382.  
  383.    INPUTS
  384.    PCIconfDev - a valid PCIConfDev structure.
  385.  
  386.    RESULTS
  387.  
  388.    EXCEPTIONS
  389.  
  390.    SEE ALSO
  391.    AddPCIDev
  392.  
  393.    BUGS
  394.  
  395.  
  396.